Manipulating Files

Inside Macintosh: Programming With MRJToolkit /: Chapter 1 - Using MRJToolkit

Manipulating Files
At times you might want to save files to a Mac OS disk drive from your Java application (such as a text document or a preferences file). While saving files to the Mac OS platform is simple, accessing them afterwards can be more problematic, since files created by a Java application do not normally contain any Mac OS-specific information and therefore cannot be assigned a custom desktop icon. A plain file without a custom icon offers the user no clues as to what application created the file or what its contents may be. Attempts to open such a file from the Mac OS Finder (the system application that manages files and the desktop) may not work, since the Finder does not know which application it should use to open it.
To solve this problem, MRJToolkit allows you to assign special Mac OS identifiers to files saved from Java applications. You can then open or search for such files just as you could from a Mac OS application. MRJToolkit also allows you to search for specific applications or special folders (such as the Preferences folder).

File Types and Creators
To identify and handle files properly, the Mac OS Finder requires two 4-byte identifiers: the file type and the creator. A file type is a string that specifies the contents of a file. For example, the file type 'APPL' identifies the file as an application and therefore executable. A file type of 'TEXT' means that the file contains raw text. Any application that can read raw text can open a file of type 'TEXT'.
However, many applications create files that contain application-specific information. For example, a word processor document might contain formatting and style information in addition to the raw text. Since only the application that created it can make use of the information, the application often assigns the file a proprietary file type.
To identify the application that created a document, the Finder relies on a string called a creator. For example, the SimpleText application (the default text editor installed with Mac OS system software) assigns the creator 'ttxt' to all its documents. If you double-click on a document that has the 'ttxt' creator, the Finder knows to look for the SimpleText application to open it (the application also bears the creator 'ttxt'). The Finder also uses the creator to assign the "correct" icon to a file so that users can tell what application created it. Creators also allow the Finder to provide useful information about a file when you select the Get Info item in the File menu.

Note
Creators may not necessarily indicate the actual creator of a file, but rather what application should open it. For example, if you use an editor to create an HTML document, you might want to assign a browser's creator ot the file rather than the HTML editor's creator. Double-clicking on the document then opens the appropriate browser rather than the HTML editor.
The MRJToolkit class com.apple.mrj.MRJFileUtils contains a number of methods that you can use to set the file type and creator of a file.
If you plan to publicly distribute your application, you must register its creator and any proprietary file types with Apple through Developer Technical Support to avoid collisions between names used by different developers. You can register a creator online or view currently registered creators at the following Web site:
http://developer.apple.com/dev/cftype/main.html
For more detailed information about how the Finder handles file types and creators, see the "Finder Interface" chapter in Inside Macintosh: Macintosh Toolbox Essentials.

The MRJOSType Data Type
The Mac OS designates the data type OSType to hold file types, creators, or the name of a folder. MRJToolkit allows access to OSType data through a wrapper object of type MRJOSType. You manipulate an MRJ OS type in the Java environment just as you would a Mac OS type in the Mac OS environment.

Setting the Default File Type and Creator
When packaging your Java application JBindery assigns the default creator you specify (or '????' if you do not choose one) and assumes that all files created by the application will have the file type 'TEXT'. To override these settings, you use the setDefaultFileType and setDefaultCreator methods. Any files that your application creates will then automatically have these default values set. Listing 1-1 sets the default creator and file type and creates a file on the Mac OS.
Listing 1-1 Setting the default file type and creator
import com.apple.mrj.*;
import java.io.*;

...

public static void testFileUtils() {
      /* first, set the current file and creator */
      MRJOSType newType = new MRJOSType("TEXT");
      MRJOSType newCreator = new MRJOSType("ttxt");
   
      MRJFileUtils.setDefaultFileType(newType);
      MRJFileUtils.setDefaultFileCreator(newCreator);
            
      /* create a File object with the current file and creator */
      File f = new File("TestFile");
      
      if (f.exists())
         f.delete();
      
      try {
         PrintStream ps = new PrintStream(new FileOutputStream(f));
         ps.println("Hello, World");
         ps.close();
         } 
      catch (IOException e) {
         fail("Failed to write output file", e);
         return;
         }
The created file TestFile has the file type 'TEXT' and the creator 'ttxt', indicating that it is a text file and should be opened using SimpleText. Since no path was specified, TestFile appears in the default directory (typically the application's directory).

Setting or Reading File Types and Creators for Existing Files
Sometimes you may want to determine or set a file type or creator for a file that already exists. For example, if the user requests that a file be opened, the application might check the file type to make sure it can handle that type of file. You can read the file type and creator using the getFileType and getFileCreator methods respectively. To set the file type and creator, you can use either the setFileType and setFileCreator methods or the setFileTypeAndCreator method. The code fragment in Listing 1-2 shows an example of reading and setting the file type and creator.
Listing 1-2 Reading and setting the file type and creator
try {
      MRJOSType curType = MRJFileUtils.getFileType(f);
      MRJOSType curCreator = MRJFileUtils.getFileCreator(f);
      
      // make sure they're what we expect
      if (! (curType.equals(new MRJOSType ("TEXT") &&            curCreator.equals(new MRJOSType ("ttxt"))))
         throw new IOException("Unexpected file type or creator");
   } catch (IOException e) {
      fail("Couldn't get file type or creator", e);
      return;
      }
   
try {
   MRJFileUtils.setFileTypeAndCreator(f, new MRJOSType("TEXT"), 
         new MRJOSType("CWIE"));
   } catch (Exception e) {
      fail("Can't set file type and creator", e);
      return;
      }
This example checks to see if the file in question is a SimpleText text file (file type 'TEXT', creator 'ttxt'). If so, it then changes the file type and creator to be that of a CodeWarrior text file. Note that since the file type is not changed, you could have called the setFileCreator method to just set the creator to 'CWIE'. After changing the creator, double-clicking on the file causes the file to be opened using CodeWarrior rather than SimpleText.

Finding an Application With a Given Creator
If you want to find an application with a given creator, you can call the findApplication method. For example, if you have an HTML file with a given browser's creator, you can search for the browser and then open the file with it. The code fragment in Listing 1-3 searches for the SimpleText application and then launches it by passing the file to Runtime.runtime.exec. (In a similar manner, you could search for a browser and have it open a local HTML file.)
Listing 1-3 Finding the path to an application
try {
      File cw = MRJFileUtils.findApplication(new MRJOSType("ttxt"));

      // launch SimpleText with our new text file
      String params[] = { cw.toString(), f.toString() };

      // parameters to runtime exec:
      // { AppToRun, FileToOpen, ... }
      Runtime.getRuntime().exec(params);

   } catch (Exception e) {
      fail("Can't find SimpleText", e);
      return;
      }
The findApplication method searches the Mac OS desktop database looking for an application with the correct creator. If more than one copy of the application exists, findApplication may find a copy different from the one you expect, depending on the state of the desktop database.

Finding Special Folders
The Mac OS platform has numerous special folders (that is, directories) that contain specialized files. For example, system extensions are stored in the Extensions folder, while fonts are stored in the Fonts folder. If your Java application accesses or saves files on the Mac OS platform, you may need to find the path to a special folder. For example, if you want to save application default settings, you should store these in the Preferences folder.
To find the path to a particular folder, you must call the findFolder method while specifying the folder you want to locate. Listing 1-4 shows a code fragment that locates the System folder and prints out the path to standard output.
Listing 1-4 Finding the System folder
try {
      System.out.println("Preferences folder is: " +
         MRJFileUtils.findFolder(
         MRJFileUtils.kPreferencesFolderType));
      } 
catch (FileNotFoundException e) {
      fail("Couldn't get Preferences folder", e);
      return;
      }
The kSystemFolderType constant specifies that you are looking for the System folder. See "Special Folder Constants" (page 32) for a complete listing of possible folders and their constants.

Subtopics
File Types and Creators

The MRJOSType Data Type

Setting the Default File Type and Creator

Setting or Reading File Types and Creators for Existing Files

Finding an Application With a Given Creator

Finding Special Folders